home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / pcl / docs.lha / cmu-user / cmu-user.info-2 < prev    next >
Text File  |  1992-08-05  |  53KB  |  1,471 lines
  1. Info file: cmu-user.info,    -*-Text-*-
  2. produced by latexinfo-format-buffer
  3. from file: cmu-user.tex
  4.  
  5.  
  6. 
  7. File: cmu-user.info  Node: The Reader, Prev: Load, Up: Design Choices and Extensions, Next: Running Programs from Lisp
  8.  
  9. The Reader
  10. ==========
  11.  
  12.  
  13.  
  14.  
  15.  -- Variable: *ignore-extra-close-parentheses*
  16.      If this variable is true (the default), then the reader merely prints a
  17.      warning when an extra close parenthesis is detected (instead of signalling an
  18.      error.)
  19.  
  20.  
  21.  
  22.  
  23. 
  24. File: cmu-user.info  Node: Running Programs from Lisp, Prev: The Reader, Up: Design Choices and Extensions, Next: Saving a Core Image
  25.  
  26. Running Programs from Lisp
  27. ==========================
  28.  
  29.  
  30. It is possible to run programs from Lisp by using the following
  31. function.
  32.  
  33.  
  34.  
  35.  -- Function: run-program 
  36.        PROGRAM ARGS
  37.        &keys :env :wait :pty :input
  38.              :if-input-does-not-exist
  39.              :output ...
  40.  
  41.      `Run-program' runs PROGRAM in a child process.  PROGRAM should be a
  42.      pathname or string naming the program.  ARGS should be a list of
  43.      strings which this passes to PROGRAM as normal Unix parameters.
  44.      For no arguments, specify ARGS as nil.  The value returned is
  45.      either a process structure or nil.  The process interface follows
  46.      the description of `run-program'.  If `run-program' fails to fork
  47.      the child process, it returns nil.
  48.      
  49.      Except for sharing file descriptors as explained in keyword
  50.      argument descriptions, `run-program' closes all file descriptors in
  51.      the child process before running the program.  When you are done
  52.      using a process, call `process-close' to reclaim system resources.
  53.      You only need to do this when you supply :stream for one of :input,
  54.      :output, or :error, or you supply :pty non-nil.  You can call
  55.      `process-close' regardless of whether you must to reclaim resources
  56.      without penalty if you feel safer.
  57.      
  58.      `run-program' accepts the following keyword arguments:
  59.           
  60.      :env     
  61.           
  62.           This is an a-list mapping keywords and simple-strings.  The
  63.           default is `ext:*environment-list*'.  If :env is specified,
  64.           `run-program' uses the value given and does not combine the
  65.           environment passed to Lisp with the one specified.
  66.           
  67.      :wait     
  68.           
  69.           If non-nil (the default), wait until the child process
  70.           terminates.  If nil, continue running Lisp while the child
  71.           process runs.
  72.           
  73.      :pty     
  74.           
  75.           This should be one of true, nil, or a stream.  If specified
  76.           non-nil, the subprocess executes under a Unix PTY.  If
  77.           specified as a stream, the system collects all output to this
  78.           pty and writes it to this stream.  If specified as true, the
  79.           `process-pty' slot contains a stream from which you can read
  80.           the program's output and to which you can write input for the
  81.           program.  The default is nil.
  82.           
  83.      :input     
  84.           
  85.           This specifies how the program gets its input.  If specified
  86.           as a string, it is the name of a file that contains input for
  87.           the child process.  `run-program' opens the file as standard
  88.           input.  If specified as nil (the default), then standard input
  89.           is the file `/dev/null'.  If specified as true, the program
  90.           uses the current standard input.  This may cause some
  91.           confusion if :wait is nil since two processes may use the
  92.           terminal at the same time.  If specified as :stream, then the
  93.           `process-input' slot contains an output stream.  Anything
  94.           written to this stream goes to the program as input.  :Input
  95.           may also be an input stream that already contains all the
  96.           input for the process.  In this case `run-program' reads all
  97.           the input from this stream before returning, so this cannot be
  98.           used to interact with the process.
  99.           
  100.      :if-input-does-not-exist     
  101.           
  102.           This specifies what to do if the input file does not exist.
  103.           The following values are valid: nil (the default) causes
  104.           `run-program' to return nil without doing anything; :create
  105.           creates the named file; and :error signals an error.
  106.           
  107.      :output     
  108.           
  109.           This specifies what happens with the program's output.  If
  110.           specified as a pathname, it is the name of a file that
  111.           contains output the program writes to its standard output.  If
  112.           specified as nil (the default), all output goes to
  113.           `/dev/null'.  If specified as true, the program writes to the
  114.           Lisp process's standard output.  This may cause confusion if
  115.           :wait is nil since two processes may write to the terminal at
  116.           the same time.  If specified as :stream, then the
  117.           `process-output' slot contains an input stream from which you
  118.           can read the program's output.
  119.           
  120.      :if-output-exists     
  121.           
  122.           This specifies what to do if the output file already exists.
  123.           The following values are valid: nil causes `run-program' to
  124.           return nil without doing anything; :error (the default)
  125.           signals an error; :supersede overwrites the current file; and
  126.           :append appends all output to the file.
  127.           
  128.      :error     
  129.           
  130.           This is similar to :output, except the file becomes the
  131.           program's standard error.  Additionally, :error can be :output
  132.           in which case the program's error output is routed to the same
  133.           place specified for :output.  If specified as :stream, the
  134.           `process-error' contains a stream similar to the
  135.           `process-output' slot when specifying the :output argument.
  136.           
  137.      :if-error-exists     
  138.           
  139.           This specifies what to do if the error output file already
  140.           exists.  It accepts the same values as :if-output-exists.
  141.           
  142.      :status-hook     
  143.           
  144.           This specifies a function to call whenever the process changes
  145.           status.  This is especially useful when specifying :wait as
  146.           nil.  The function takes the process as a required argument.
  147.           
  148.      :before-execve     
  149.           
  150.           This specifies a function to run in the child process before
  151.           it becomes the program to run.  This is useful for actions
  152.           such as authenticating the child process without modifying the
  153.           parent Lisp process.
  154.      
  155.      
  156.  
  157.  
  158.  
  159. * Menu:
  160.  
  161. * Process Accessors::           
  162.  
  163.  
  164. 
  165. File: cmu-user.info  Node: Process Accessors, Prev: Running Programs from Lisp, Up: Running Programs from Lisp
  166.  
  167. Process Accessors
  168. -----------------
  169.  
  170.  
  171. The following functions interface the process returned by `run-program':
  172.  
  173.  
  174.  -- Function: process-p THING
  175.  
  176.      This function returns true if THING is a process.  Otherwise it returns
  177.      nil
  178.  
  179.  
  180.  
  181.  -- Function: process-pid PROCESS
  182.  
  183.      This function returns the process ID, an integer, for the PROCESS.
  184.  
  185.  
  186.  
  187.  -- Function: process-status PROCESS
  188.  
  189.      This function returns the current status of PROCESS, which is one
  190.      of `:running', `:stopped', `:exited', or `:signaled'.
  191.  
  192.  
  193.  
  194.  -- Function: process-exit-code PROCESS
  195.  
  196.      This function returns either the exit code for PROCESS, if it is
  197.      `:exited', or the termination signal PROCESS if it is `:signaled'.
  198.      The result is undefined for processes that are still alive.
  199.  
  200.  
  201.  
  202.  -- Function: process-core-dumped PROCESS
  203.  
  204.      This function returns true if someone used a Unix signal to
  205.      terminate the PROCESS and caused it to dump a Unix core image.
  206.  
  207.  
  208.  
  209.  -- Function: process-pty PROCESS
  210.  
  211.      This function returns either the two-way stream connected to
  212.      PROCESS's Unix PTY connection or nil if there is none.
  213.  
  214.  
  215.  
  216.  -- Function: process-input PROCESS
  217.  
  218.  -- Function: process-output PROCESS
  219.  
  220.  -- Function: process-error PROCESS
  221.  
  222.      If the corresponding stream was created, these functions return the
  223.      input, output or error file descriptor.  nil is returned if there
  224.      is no stream.
  225.  
  226.  
  227.  
  228.  -- Function: process-status-hook PROCESS
  229.  
  230.      This function returns the current function to call whenever
  231.      PROCESS's status changes.  This function takes the PROCESS as a
  232.      required argument.  `process-status-hook' is `setf''able.
  233.  
  234.  
  235.  
  236.  -- Function: process-plist PROCESS
  237.  
  238.      This function returns annotations supplied by users, and it is
  239.      `setf''able.  This is available solely for users to associate
  240.      information with PROCESS without having to build a-lists or hash
  241.      tables of process structures.
  242.  
  243.  
  244.  
  245.   -- Function: process-wait 
  246.         PROCESS &optional CHECK-FOR-STOPPED
  247.  
  248.      This function waits for PROCESS to finish.  If CHECK-FOR-STOPPED is
  249.      non-nil, this also returns when PROCESS stops.
  250.  
  251.  
  252.  
  253.   -- Function: process-kill 
  254.         process signal &optional WHOM
  255.  
  256.      This function sends the Unix SIGNAL to PROCESS.  SIGNAL should be
  257.      the number of the signal or a keyword with the Unix name (for example,
  258.      :sigsegv).  WHOM should be one of the following:
  259.           
  260.      :pid     
  261.           
  262.           This is the default, and it indicates sending the signal to
  263.           PROCESS only.
  264.           
  265.      :process-group     
  266.           
  267.           This indicates sending the signal to PROCESS's group.
  268.           
  269.      :pty-process-group     
  270.           
  271.           This indicates sending the signal to the process group
  272.           currently in the foreground on the Unix PTY connected to
  273.           PROCESS.  This last option is useful if the running program is
  274.           a shell, and you wish to signal the program running under the
  275.           shell, not the shell itself.  If `process-pty' of PROCESS is
  276.           nil, using this option is an error.
  277.      
  278.  
  279.  
  280.  
  281.  -- Function: process-alive-p PROCESS
  282.  
  283.      This function returns true if PROCESS's status is either `:running'
  284.      or `:stopped'.
  285.  
  286.  
  287.  
  288.  -- Function: process-close PROCESS
  289.  
  290.      This function closes all the streams associated with PROCESS.  When
  291.      you are done using a process, call this to reclaim system
  292.      resources.
  293.  
  294.  
  295.  
  296. 
  297. File: cmu-user.info  Node: Saving a Core Image, Prev: Running Programs from Lisp, Up: Design Choices and Extensions, Next: Search Lists
  298.  
  299. Saving a Core Image
  300. ===================
  301.  
  302.  
  303. A mechanism has been provided to save a running Lisp core image and to
  304. later restore it.  This is convenient if you don't want to load several
  305. files into a Lisp when you first start it up.  The main problem is the
  306. large size of each saved Lisp image, typically at least 20 megabytes.
  307.  
  308.  
  309.  -- Function: save-lisp 
  310.        FILE
  311.        &keys :purify :root-structures :init-function
  312.              :load-init-file :print-herald
  313.              :process-command-line
  314.  
  315.      The `save-lisp' function saves the state of the currently running Lisp
  316.      core image in FILE.  The keyword arguments have the following meaning:
  317.           
  318.      :purify     
  319.           
  320.           If non-NIL (the default), the core image is purified before it
  321.           is saved.  This means moving accessible Lisp objects from
  322.           dynamic space into read-only and static space.  This reduces
  323.           the amount of work the garbage collector must do when the
  324.           resulting core image is being run.  Also, if more than one
  325.           Lisp is running on the same machine, this maximizes the amount
  326.           of memory that can be shared between the two processes.
  327.           Objects in read-only and static space can never be reclaimed,
  328.           even if all pointers to them are dropped.
  329.           
  330.      :root-structures     
  331.           
  332.           This should be a list of the main entry points for the
  333.           resulting core image.  The purification process tries to
  334.           localize symbols, functions, etc., in the core image so that
  335.           paging performance is improved.  The default value is NIL
  336.           which means that Lisp objects will still be localized but
  337.           probably not as optimally as they could be.  This argument has
  338.           no meaning if :purify is NIL.
  339.           
  340.      :init-function     
  341.           
  342.           This is a function which is called when the saved core is
  343.           resumed.  The default function simply aborts to the top-level
  344.           read-eval-print loop.  If the function returns, it will be the
  345.           value of `save-lisp'.
  346.           
  347.      :load-init-file     
  348.           
  349.           If non-NIL, then load an init file; either the one specified
  350.           on the command line or "`init.'FASL-TYPE", or, if
  351.           "`init.'FASL-TYPE" does not exist, `init.lisp' from the user's
  352.           home directory.  If the init file is found, it is loaded into
  353.           the resumed core file before the read-eval-print loop is
  354.           entered.
  355.           
  356.      :print-herald     
  357.           
  358.           If non-NIL, then print out the standard Lisp herald when
  359.           starting.
  360.           
  361.      :process-command-line     
  362.           
  363.           If non-NIL, processes the command line switches and performs
  364.           the appropriate actions.
  365.      
  366.  
  367.  
  368. To resume a saved file, type:
  369.      
  370.      lisp -core file
  371.  
  372.  
  373.  
  374. 
  375. File: cmu-user.info  Node: Search Lists, Prev: Saving a Core Image, Up: Design Choices and Extensions, Next: Time Parsing and Formatting
  376.  
  377. Search Lists
  378. ============
  379.  
  380.  
  381. Search lists are an extension to Common Lisp pathnames.  Search lists are used
  382. for two purposes:
  383.    * They provide a convenient shorthand for commonly used directory names,
  384.      and
  385.      
  386.    * They allow the abstract (directory structure independent) specification
  387.      of file locations in program pathname constants (similar to logical pathnames.)
  388.  
  389. Each search list has an associated list of directories (represented as
  390. pathnames with no name or type component.)  The namestring for any
  391. relative pathname may be prefixed with "SLIST`:'", indicating that the
  392. pathname is relative to the search list SLIST (instead of to the current
  393. working directory.)  Once qualified with a search list, the pathname is
  394. no longer considered to be relative.
  395.  
  396. When a search list qualified pathname is passed to a file-system
  397. operation such as `open', `load' or `truename', each directory in the
  398. search list is successively used as the root of the pathname until the
  399. file is located.  When a file is written to a search list directory, the
  400. file is always written to the first directory in the list.
  401.  
  402.  
  403.  -- Function: search-list NAME
  404.  
  405.      This function returns the list of directories associated with the
  406.      search list NAME.  If NAME is not a defined search list, then an
  407.      error is signalled.  When set with `setf', the list of directories
  408.      is changed to the new value.  If the new value is just a namestring
  409.      or pathname, then it is interpreted as a one-element list.  Note
  410.      that (unlike Unix pathnames), search list names are
  411.      case-insensitive.
  412.  
  413.  
  414.  
  415.  -- Function: search-list-defined-p NAME
  416.  
  417.  -- Function: clear-search-list NAME
  418.  
  419.      `search-list-defined-p' returns true if NAME is a defined search
  420.      list name, false otherwise.  `clear-search-list' make the search
  421.      list NAME undefined.
  422.  
  423.  
  424.  
  425.  
  426.  -- Macro: enumerate-search-list 
  427.  (VAR PATHNAME [result])
  428.  {form}*
  429.  
  430.      This macro provides an interface to search list resolution.  The
  431.      body FORMS are executed with VAR bound to each successive possible
  432.      expansion for NAME.  If NAME does not contain a search-list, then
  433.      the body is executed exactly once.  Everything is wrapped in a
  434.      block named nil, so `return' can be used to terminate early.  The
  435.      RESULT form (default nil) is evaluated to determine the result of
  436.      the iteration.
  437.  
  438.  
  439. * Menu:
  440.  
  441. * Search List Example::         
  442.  
  443.  
  444. 
  445. File: cmu-user.info  Node: Search List Example, Prev: Search Lists, Up: Search Lists
  446.  
  447. Search List Example
  448. -------------------
  449.  
  450.  
  451. The search list `code:' can be defined as follows:
  452.      
  453.      (setf (ext:search-list "code:") '("/usr/lisp/code/"))
  454.  
  455. It is now possible to use `code:' as an abbreviation for the directory
  456. `/usr/lisp/code/' in all file operations.  For example, you can now
  457. specify `code:eval.lisp' to refer to the file
  458. `/usr/lisp/code/eval.lisp'.
  459.  
  460. To obtain the value of a search-list name, use the function search-list
  461. as follows:
  462.      
  463.      (ext:search-list NAME)
  464.  
  465. Where NAME is the name of a search list as described above.  For example,
  466. calling `ext:search-list' on `code:' as follows:
  467.      
  468.      (ext:search-list "code:")
  469.  
  470. returns the list `("/usr/lisp/code/")'.
  471.  
  472.  
  473. 
  474. File: cmu-user.info  Node: Time Parsing and Formatting, Prev: Search Lists, Up: Design Choices and Extensions, Next: Lisp Library
  475.  
  476. Time Parsing and Formatting
  477. ===========================
  478.  
  479.  
  480.  
  481. Functions are provided to allow parsing strings containing time
  482. information and printing time in various formats are available.
  483.  
  484.  
  485.  -- Function: parse-time 
  486.        TIME-STRING
  487.        &keys :error-on-mismatch :default-seconds
  488.              :default-minutes :default-hours
  489.              :default-day ...
  490.  
  491.      `parse-time' accepts a string containing a time (e.g., 
  492.      "`Jan 12, 1952'")
  493.      and returns the universal time if it is successful.  If it is unsuccessful
  494.      and the keyword argument :error-on-mismatch is non-false, it signals an
  495.      error.  Otherwise it returns false.  The other keyword arguments have the
  496.      following meaning:
  497.           
  498.      :default-seconds     
  499.           
  500.           specifies the default value for the seconds value if one is
  501.           not provided by TIME-STRING.  The default value is 0.
  502.           
  503.      :default-minutes     
  504.           
  505.           specifies the default value for the minutes value if one is
  506.           not provided by TIME-STRING.  The default value is 0.
  507.           
  508.      :default-hours     
  509.           
  510.           specifies the default value for the hours value if one is not
  511.           provided by TIME-STRING.  The default value is 0.
  512.           
  513.      :default-day     
  514.           
  515.           specifies the default value for the day value if one is not
  516.           provided by TIME-STRING.  The default value is the current
  517.           day.
  518.           
  519.      :default-month     
  520.           
  521.           specifies the default value for the month value if one is not
  522.           provided by TIME-STRING.  The default value is the current
  523.           month.
  524.           
  525.      :default-year     
  526.           
  527.           specifies the default value for the year value if one is not
  528.           provided by TIME-STRING.  The default value is the current
  529.           year.
  530.           
  531.      :default-zone     
  532.           
  533.           specifies the default value for the time zone value if one is
  534.           not provided by TIME-STRING.  The default value is the current
  535.           time zone.
  536.           
  537.      :default-weekday     
  538.           
  539.           specifies the default value for the day of the week if one is
  540.           not provided by TIME-STRING.  The default value is the current
  541.           day of the week.
  542.      
  543.      Any of the above keywords can be given the value :current which
  544.      means to use the current value as determined by a call to the
  545.      operating system.
  546.  
  547.  
  548.  
  549.  
  550.  -- Function: format-universal-time 
  551.        dest universal-time
  552.        &keys :timezone
  553.              :style :date-first
  554.              :print-seconds ...
  555.  
  556.  
  557.  -- Function: format-decoded-time 
  558.               dest seconds minutes hours day month year &key ...
  559.  
  560.      `format-universal-time' formats the time specified by UNIVERSAL-TIME.
  561.      `format-decoded-time' formats the time specified by SECONDS,
  562.      MINUTES, HOURS, DAY, MONTH, and YEAR.
  563.      DEST is any destination accepted by the `format' function.
  564.      The keyword arguments have the following meaning:
  565.           
  566.      :timezone     
  567.           
  568.           is an integer specifying the hours west of Greenwich.
  569.           :Timezone defaults to the current time zone.
  570.           
  571.      :style     
  572.           
  573.           specifies the style to use in formatting the time.  The legal
  574.           values are:
  575.                
  576.           :short     
  577.                
  578.                specifies to use a numeric date.
  579.                
  580.           :long     
  581.                
  582.                specifies to format months and weekdays as words instead
  583.                of numbers.
  584.                
  585.           :abbreviated     
  586.                
  587.                is similar to long except the words are abbreviated.
  588.                
  589.           :government     
  590.                
  591.                is similar to abbreviated, except the date is of the form
  592.                "day month year" instead of "month day, year".
  593.           
  594.           
  595.      :date-first     
  596.           
  597.           if non-false (default) will place the date first.  Otherwise,
  598.           the time is placed first.
  599.           
  600.      :print-seconds     
  601.           
  602.           if non-false (default) will format the seconds as part of the
  603.           time.  Otherwise, the seconds will be omitted.
  604.           
  605.      :print-meridian     
  606.           
  607.           if non-false (default) will format "AM" or "PM" as part of the
  608.           time.  Otherwise, the "AM" or "PM" will be omitted.
  609.           
  610.      :print-timezone     
  611.           
  612.           if non-false (default) will format the time zone as part of
  613.           the time.  Otherwise, the time zone will be omitted.
  614.           
  615.      :print-seconds     
  616.           
  617.           if non-false (default) will format the seconds as part of the
  618.           time.  Otherwise, the seconds will be omitted.
  619.           
  620.      :print-weekday     
  621.           
  622.           if non-false (default) will format the weekday as part of
  623.           date.  Otherwise, the weekday will be omitted.
  624.      
  625.  
  626.  
  627.  
  628. 
  629. File: cmu-user.info  Node: Lisp Library, Prev: Time Parsing and Formatting, Up: Design Choices and Extensions
  630.  
  631. Lisp Library
  632. ============
  633.  
  634.  
  635. The CMU Common Lisp project maintains a collection of useful or interesting
  636. programs written by users of our system.  The library is in
  637. `lib/contrib/'.  Two files there that users should read are:
  638.      
  639. CATALOG.TXT     
  640.      
  641.      This file contains a page for each entry in the library.  It
  642.      contains information such as the author, portability or dependency
  643.      issues, how to load the entry, etc.
  644.      
  645. READ-ME.TXT     
  646.      
  647.      This file describes the library's organization and all the possible
  648.      pieces of information an entry's catalog description could contain.
  649.  
  650.  
  651. Hemlock has a command Library Entry that displays a list of the current
  652. library entries in an editor buffer.  There are mode specific commands
  653. that display catalog descriptions and load entries.  This is a simple
  654. and convenient way to browse the library.
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661. 
  662. File: cmu-user.info  Node: The Debugger, Prev: Design Choices and Extensions, Up: Top, Next: The Compiler
  663.  
  664. The Debugger
  665. ************
  666.  
  667.  
  668.                           By Robert MacLachlan
  669.  
  670.  
  671. * Menu:
  672.  
  673. * Debugger Introduction::       
  674. * The Command Loop::            
  675. * Stack Frames::                
  676. * Variable Access::             
  677. * Source Location Printing::    
  678. * Compiler Policy Control::     
  679. * Exiting Commands::            
  680. * Information Commands::        
  681. * Breakpoint Commands::
  682. * Function Tracing::            
  683. * Specials::                    
  684.  
  685.  
  686. 
  687. File: cmu-user.info  Node: Debugger Introduction, Prev: The Debugger, Up: The Debugger, Next: The Command Loop
  688.  
  689. Debugger Introduction
  690. =====================
  691.  
  692.  
  693. The CMU Common Lisp debugger is unique in its level of support for source-level
  694. debugging of compiled code.  Although some other debuggers allow access of
  695. variables by name, this seems to be the first Common Lisp debugger that:
  696.      
  697.    * Tells you when a variable doesn't have a value because it hasn't been
  698.      initialized yet or has already been deallocated, or
  699.      
  700.    * Can display the precise source location corresponding to a code
  701.      location in the debugged program.
  702.  
  703. These features allow the debugging of compiled code to be made almost
  704. indistinguishable from interpreted code debugging.
  705.  
  706. The debugger is an interactive command loop that allows a user to examine
  707. the function call stack.  The debugger is invoked when:
  708.      
  709.    * A serious-condition is signalled, and it is not handled, or
  710.      
  711.    * error is called, and the condition it signals is not handled, or
  712.      
  713.    * The debugger is explicitly invoked with the CMU Common Lisp break
  714.      or debug functions.
  715.  
  716. When you enter the debugger, it looks something like this:
  717.      
  718.      Error in function CAR.  Wrong type argument, 3, should have been of
  719.      type LIST.
  720.      
  721.      Restarts:
  722.        0: Return to Top-Level.
  723.      
  724.      Debug  (type H for help)
  725.      
  726.      (CAR 3)
  727.      0]
  728.  
  729. The first group of lines describe what the error was that put us in the
  730. debugger.  In this case `car' was called on `3'.  After `Restarts:' is a
  731. list of all the ways that we can restart execution after this error.  In
  732. this case, the only option is to return to top-level.  After printing
  733. its banner, the debugger prints the current frame and the debugger
  734. prompt.
  735.  
  736.  
  737. 
  738. File: cmu-user.info  Node: The Command Loop, Prev: Debugger Introduction, Up: The Debugger, Next: Stack Frames
  739.  
  740. The Command Loop
  741. ================
  742.  
  743.  
  744. The debugger is an interactive read-eval-print loop much like the normal
  745. top-level, but some symbols are interpreted as debugger commands instead
  746. of being evaluated.  A debugger command starts with the symbol name of
  747. the command, possibly followed by some arguments on the same line.  Some
  748. commands prompt for additional input.  Debugger commands can be
  749. abbreviated by any unambiguous prefix: `help' can be typed as `h', `he',
  750. etc.  For convenience, some commands have ambiguous one-letter
  751. abbreviations: `f' for `frame'.
  752.  
  753. The package is not significant in debugger commands; any symbol with the
  754. name of a debugger command will work.  If you want to show the value of
  755. a variable that happens also to be the name of a debugger command, you
  756. can use the `list-locals' command or the `debug:var' function, or you
  757. can wrap the variable in a `progn' to hide it from the command loop.
  758.  
  759. The debugger prompt is "FRAME`]'", where FRAME is the number of the
  760. current frame.  Frames are numbered starting from zero at the top (most
  761. recent call), increasing down to the bottom.  The current frame is the
  762. frame that commands refer to.  The current frame also provides the
  763. lexical environment for evaluation of non-command forms.
  764.  
  765. environment of the functions being debugged.  The debugger can only
  766. access variables.  You can't `go' or `return-from' into a function, and
  767. you can't call local functions.  Special variable references are
  768. evaluated with their current value (the innermost binding around the
  769. debugger invocation) -- you don't get the value that the special had in
  770. the current frame.  ? for more information on debugger variable access.
  771.  
  772.  
  773. 
  774. File: cmu-user.info  Node: Stack Frames, Prev: The Command Loop, Up: The Debugger, Next: Variable Access
  775.  
  776. Stack Frames
  777. ============
  778.  
  779.  
  780. A stack frame is the run-time representation of a call to a function;
  781. the frame stores the state that a function needs to remember what it is
  782. doing.  Frames have:
  783.      
  784.    * Variables (?), which are the values being operated
  785.      on, and
  786.      
  787.    * Arguments to the call (which are really just particularly interesting
  788.      variables), and
  789.      
  790.    * A current location (?), which is the place in the program where the
  791.      function was running when it stopped to call another function, or
  792.      because of an interrupt or error.
  793.  
  794.  
  795.  
  796.  
  797. * Menu:
  798.  
  799. * Stack Motion::                
  800. * How Arguments are Printed::   
  801. * Function Names::              
  802. * Funny Frames::                
  803. * Debug Tail Recursion::        
  804. * Unknown Locations and Interrupts::  
  805.  
  806.  
  807. 
  808. File: cmu-user.info  Node: Stack Motion, Prev: Stack Frames, Up: Stack Frames, Next: How Arguments are Printed
  809.  
  810. Stack Motion
  811. ------------
  812.  
  813.  
  814. These commands move to a new stack frame and print the name of the function
  815. and the values of its arguments in the style of a Lisp function call:
  816.      
  817. `up'     
  818.      
  819.      Move up to the next higher frame.  More recent function calls are
  820.      considered to be higher on the stack.
  821.      
  822. `down'     
  823.      
  824.      Move down to the next lower frame.
  825.      
  826. `top'     
  827.      
  828.      Move to the highest frame.
  829.      
  830. `bottom'     
  831.      
  832.      Move to the lowest frame.
  833.      
  834. `frame' [N]     
  835.      
  836.      Move to the frame with the specified number.  Prompts for the
  837.      number if not supplied.
  838.      
  839.  
  840.  
  841. 
  842. File: cmu-user.info  Node: How Arguments are Printed, Prev: Stack Motion, Up: Stack Frames, Next: Function Names
  843.  
  844. How Arguments are Printed
  845. -------------------------
  846.  
  847.  
  848. A frame is printed to look like a function call, but with the actual argument
  849. values in the argument positions.  So the frame for this call in the source:
  850.      
  851.      (myfun (+ 3 4) 'a)
  852.  
  853. would look like this:
  854.      
  855.      (MYFUN 7 A)
  856.  
  857. All keyword and optional arguments are displayed with their actual
  858. values; if the corresponding argument was not supplied, the value will
  859. be the default.  So this call:
  860.      
  861.      (subseq "foo" 1)
  862.  
  863. would look like this:
  864.      
  865.      (SUBSEQ "foo" 1 3)
  866.  
  867. And this call:
  868.      
  869.      (string-upcase "test case")
  870.  
  871. would look like this:
  872.      
  873.      (STRING-UPCASE "test case" :START 0 :END NIL)
  874.  
  875.  
  876. The arguments to a function call are displayed by accessing the argument
  877. variables.  Although those variables are initialized to the actual
  878. argument values, they can be set inside the function; in this case the
  879. new value will be displayed.
  880.  
  881. `&rest' arguments are handled somewhat differently.  The value of
  882. the rest argument variable is displayed as the spread-out arguments to
  883. the call, so:
  884.      
  885.      (format t "~A is a ~A." "This" 'test)
  886.  
  887. would look like this:
  888.      
  889.      (FORMAT T "~A is a ~A." "This" 'TEST)
  890.  
  891. Rest arguments cause an exception to the normal display of keyword
  892. arguments in functions that have both `&rest' and `&key' arguments.  In
  893. this case, the keyword argument variables are not displayed at all; the
  894. rest arg is displayed instead.  So for these functions, only the
  895. keywords actually supplied will be shown, and the values displayed will
  896. be the argument values, not values of the (possibly modified) variables.
  897.  
  898. If the variable for an argument is never referenced by the function, it
  899. will be deleted.  The variable value is then unavailable, so the
  900. debugger prints `<unused-arg>' instead of the value.  Similarly, if for
  901. any of a number of reasons (described in more detail in section ?) the
  902. value of the variable is unavailable or not known to be available, then
  903. `<unavailable-arg>' will be printed instead of the argument value.
  904.  
  905. Printing of argument values is controlled by `*debug-print-level*' and
  906. debug-print-length ?.
  907.  
  908.  
  909. 
  910. File: cmu-user.info  Node: Function Names, Prev: How Arguments are Printed, Up: Stack Frames, Next: Funny Frames
  911.  
  912. Function Names
  913. --------------
  914.  
  915.  
  916. If a function is defined by `defun', `labels', or `flet', then the
  917. debugger will print the actual function name after the open parenthesis, like:
  918.      
  919.      (STRING-UPCASE "test case" :START 0 :END NIL)
  920.      ((SETF AREF) #\a "for" 1)
  921.  
  922. Otherwise, the function name is a string, and will be printed in quotes:
  923.      
  924.      ("DEFUN MYFUN" BAR)
  925.      ("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
  926.      ("SETQ *GC-NOTIFY-BEFORE*")
  927.  
  928. This string name is derived from the `def'MUMBLE form that encloses or
  929. expanded into the lambda, or the outermost enclosing form if there is no
  930. `def'MUMBLE.
  931.  
  932.  
  933. 
  934. File: cmu-user.info  Node: Funny Frames, Prev: Function Names, Up: Stack Frames, Next: Debug Tail Recursion
  935.  
  936. Funny Frames
  937. ------------
  938.  
  939.  
  940. Sometimes the evaluator introduces new functions that are used to
  941. implement a user function, but are not directly specified in the source.
  942. The main place this is done is for checking argument type and syntax.
  943. Usually these functions do their thing and then go away, and thus are
  944. not seen on the stack in the debugger.  But when you get some sort of
  945. error during lambda-list processing, you end up in the debugger on one
  946. of these funny frames.
  947.  
  948. These funny frames are flagged by printing "`['KEYWORD`]'" after the
  949. parentheses.  For example, this call:
  950.      
  951.      (car 'a 'b)
  952.  
  953. will look like this:
  954.      
  955.      (CAR 2 A) [:EXTERNAL]
  956.  
  957. And this call:
  958.      
  959.      (string-upcase "test case" :end)
  960.  
  961. would look like this:
  962.      
  963.      ("DEFUN STRING-UPCASE" "test case" 335544424 1) [:OPTIONAL]
  964.  
  965.  
  966. As you can see, these frames have only a vague resemblance to the original
  967. call.  Fortunately, the error message displayed when you enter the debugger
  968. will usually tell you what problem is (in these cases, too many arguments
  969. and odd keyword arguments.)  Also, if you go down the stack to the frame for
  970. the calling function, you can display the original source (?.)
  971.  
  972. With recursive or block compiled functions (?), an `:EXTERNAL' frame may
  973. appear before the frame representing the first call to the recursive
  974. function or entry to the compiled block.  This is a consequence of the
  975. way the compiler does block compilation: there is nothing odd with your
  976. program.  You will also see `:CLEANUP' frames during the execution of
  977. `unwind-protect' cleanup code.  Note that inline expansion and
  978. open-coding affect what frames are present in the debugger, see sections
  979. ? and ?.
  980.  
  981.  
  982. 
  983. File: cmu-user.info  Node: Debug Tail Recursion, Prev: Funny Frames, Up: Stack Frames, Next: Unknown Locations and Interrupts
  984.  
  985. Debug Tail Recursion
  986. --------------------
  987.  
  988.  
  989. Both the compiler and the interpreter are "properly tail recursive."  If a
  990. function call is in a tail-recursive position, the stack frame will be
  991. deallocated at the time of the call, rather than after the call returns.
  992. Consider this backtrace:
  993.      
  994.      (BAR ...) 
  995.      (FOO ...)
  996.  
  997. Because of tail recursion, it is not necessarily the case that
  998. `FOO' directly called `BAR'.  It may be that `FOO' called
  999. some other function `FOO2' which then called `BAR'
  1000. tail-recursively, as in this example:
  1001.      
  1002.      (defun foo ()
  1003.        ...
  1004.        (foo2 ...)
  1005.        ...)
  1006.      
  1007.      (defun foo2 (...)
  1008.        ...
  1009.        (bar ...))
  1010.      
  1011.      (defun bar (...)
  1012.        ...)
  1013.  
  1014.  
  1015. Usually the elimination of tail-recursive frames makes debugging more
  1016. pleasant, since theses frames are mostly uninformative.  If there is any
  1017. doubt about how one function called another, it can usually be
  1018. eliminated by finding the source location in the calling frame (section
  1019. ?.)
  1020.  
  1021. For a more thorough discussion of tail recursion, ?.
  1022.  
  1023.  
  1024. 
  1025. File: cmu-user.info  Node: Unknown Locations and Interrupts, Prev: Debug Tail Recursion, Up: Stack Frames
  1026.  
  1027. Unknown Locations and Interrupts
  1028. --------------------------------
  1029.  
  1030.  
  1031. The debugger operates using special debugging information attached to
  1032. the compiled code.  This debug information tells the debugger what it
  1033. needs to know about the locations in the code where the debugger can be
  1034. invoked.  If the debugger somehow encounters a location not described in
  1035. the debug information, then it is said to be UNKNOWN.  If the code
  1036. location for a frame is unknown, then some variables may be
  1037. inaccessible, and the source location cannot be precisely displayed.
  1038.  
  1039. There are three reasons why a code location could be unknown:
  1040.      
  1041.    * There is inadequate debug information due to the value of the
  1042.      `debug' optimization quality.  ?.
  1043.      
  1044.    * The debugger was entered because of an interrupt such as `^C'.
  1045.      
  1046.    * A hardware error such as "`bus error'" occurred in code that was
  1047.      compiled unsafely due to the value of the `safety' optimization
  1048.      quality.  ?.
  1049.  
  1050.  
  1051. In the last two cases, the values of argument variables are accessible,
  1052. but may be incorrect.  ? for more details on when variable values are
  1053. accessible.
  1054.  
  1055. It is possible for an interrupt to happen when a function call or return
  1056. is in progress.  The debugger may then flame out with some obscure error
  1057. or insist that the bottom of the stack has been reached, when the real
  1058. problem is that the current stack frame can't be located.  If this
  1059. happens, return from the interrupt and try again.
  1060.  
  1061. When running interpreted code, all locations should be known.  However,
  1062. an interrupt might catch some subfunction of the interpreter at an
  1063. unknown location.  In this case, you should be able to go up the stack a
  1064. frame or two and reach an interpreted frame which can be debugged.
  1065.  
  1066.  
  1067. 
  1068. File: cmu-user.info  Node: Variable Access, Prev: Stack Frames, Up: The Debugger, Next: Source Location Printing
  1069.  
  1070. Variable Access
  1071. ===============
  1072.  
  1073.  
  1074. There are three ways to access the current frame's local variables in
  1075. the debugger.  The simplest is to type the variable's name into the
  1076. debugger's read-eval-print loop.  The debugger will evaluate the
  1077. variable reference as though it had appeared inside that frame.
  1078.  
  1079. The debugger doesn't really understand lexical scoping; it has just one
  1080. namespace for all the variables in a function.  If a symbol is the name
  1081. of multiple variables in the same function, then the reference appears
  1082. ambiguous, even though lexical scoping specifies which value is visible
  1083. at any given source location.  If the scopes of the two variables are
  1084. not nested, then the debugger can resolve the ambiguity by observing
  1085. that only one variable is accessible.
  1086.  
  1087. When there are ambiguous variables, the evaluator assigns each one a
  1088. small integer identifier.  The `debug:var' function and the
  1089. `list-locals' command use this identifier to distinguish between
  1090. ambiguous variables:
  1091.      
  1092. `list-locals' [PREFIX]     
  1093.      This command prints the name and value of all variables in the
  1094.      current frame whose name has the specified PREFIX.  PREFIX may be a
  1095.      string or a symbol.  If no PREFIX is given, then all available
  1096.      variables are printed.  If a variable has a potentially ambiguous
  1097.      name, then the name is printed with a "`#'IDENTIFIER" suffix, where
  1098.      IDENTIFIER is the small integer used to make the name unique.
  1099.  
  1100.  
  1101.  
  1102.  -- Function: var NAME &optional IDENTIFIER
  1103.  
  1104.      This function returns the value of the variable in the current
  1105.      frame with the specified NAME.  If supplied, IDENTIFIER determines
  1106.      which value to return when there are ambiguous variables.
  1107.      
  1108.      When NAME is a symbol, it is interpreted as the symbol name of the
  1109.      variable, i.e. the package is significant.  If NAME is an
  1110.      uninterned symbol (gensym), then return the value of the uninterned
  1111.      variable with the same name.  If NAME is a string, `debug:var'
  1112.      interprets it as the prefix of a variable name, and must
  1113.      unambiguously complete to the name of a valid variable.
  1114.      
  1115.      This function is useful mainly for accessing the value of
  1116.      uninterned or ambiguous variables, since most variables can be
  1117.      evaluated directly.
  1118.  
  1119.  
  1120.  
  1121. * Menu:
  1122.  
  1123. * Variable Value Availability::  
  1124. * Note On Lexical Variable Access::  
  1125.  
  1126.  
  1127. 
  1128. File: cmu-user.info  Node: Variable Value Availability, Prev: Variable Access, Up: Variable Access, Next: Note On Lexical Variable Access
  1129.  
  1130. Variable Value Availability
  1131. ---------------------------
  1132.  
  1133.  
  1134. The value of a variable may be unavailable to the debugger in portions
  1135. of the program where CMU Common Lisp says that the variable is defined.
  1136. If a variable value is not available, the debugger will not let you read
  1137. or write that variable.  With one exception, the debugger will never
  1138. display an incorrect value for a variable.  Rather than displaying
  1139. incorrect values, the debugger tells you the value is unavailable.
  1140.  
  1141. The one exception is this: if you interrupt (e.g., with `^C') or if
  1142. there is an unexpected hardware error such as "`bus error'" (which
  1143. should only happen in unsafe code), then the values displayed for
  1144. arguments to the interrupted frame might be incorrect. (1) (*Note
  1145. Variable Value Availability-Footnotes::) This exception applies only to
  1146. the interrupted frame: any frame farther down the stack will be fine.
  1147.  
  1148. The value of a variable may be unavailable for these reasons:
  1149.      
  1150.    * The value of the `debug' optimization quality may have omitted
  1151.      debug information needed to determine whether the variable is
  1152.      available.  Unless a variable is an argument, its value will only
  1153.      be available when `debug' is at least `2'.
  1154.      
  1155.    * The compiler did lifetime analysis and determined that the value
  1156.      was no longer needed, even though its scope had not been exited.
  1157.      Lifetime analysis is inhibited when the `debug' optimization
  1158.      quality is `3'.
  1159.      
  1160.    * The variable's name is an uninterned symbol (gensym).  To save
  1161.      space, the compiler only dumps debug information about uninterned
  1162.      variables when the `debug' optimization quality is `3'.
  1163.      
  1164.    * The frame's location is unknown (*Note Unknown Locations and
  1165.      Interrupts::) because the debugger was entered due to an interrupt
  1166.      or unexpected hardware error.  Under these conditions the values of
  1167.      arguments will be available, but might be incorrect.  This is the
  1168.      exception above.
  1169.      
  1170.    * The variable was optimized out of existence.  Variables with no
  1171.      reads are always optimized away, even in the interpreter.  The
  1172.      degree to which the compiler deletes variables will depend on the
  1173.      value of the `compile-speed' optimization quality, but most
  1174.      source-level optimizations are done under all compilation policies.
  1175.  
  1176.  
  1177.  
  1178. Since it is especially useful to be able to get the arguments to a
  1179. function, argument variables are treated specially when the `speed'
  1180. optimization quality is less than `3' and the `debug' quality is at
  1181. least `1'.  With this compilation policy, the values of argument
  1182. variables are almost always available everywhere in the function, even
  1183. at unknown locations.  For non-argument variables, `debug' must be at
  1184. least `2' for values to be available, and even then, values are only
  1185. available at known locations.
  1186.  
  1187.  
  1188. 
  1189. File: cmu-user.info  Node: Variable Value Availability-Footnotes, Up: Variable Value Availability
  1190.  
  1191. (1) Since the location of an interrupt or hardware error will always be
  1192. an unknown location (*Note Unknown Locations and Interrupts::), non-argument variable
  1193. values will never be available in the interrupted frame.
  1194.  
  1195. 
  1196. File: cmu-user.info  Node: Note On Lexical Variable Access, Prev: Variable Value Availability, Up: Variable Access
  1197.  
  1198. Note On Lexical Variable Access
  1199. -------------------------------
  1200.  
  1201.  
  1202. When the debugger command loop establishes variable bindings for
  1203. available variables, these variable bindings have lexical scope and
  1204. dynamic extent. (2) (*Note Note On Lexical Variable Access-Footnotes::)
  1205. You can close over them, but such closures can't be used as upward
  1206. funargs.
  1207.  
  1208. You can also set local variables using `setq', but if the variable was
  1209. closed over in the original source and never set, then setting the
  1210. variable in the debugger may not change the value in all the functions
  1211. the variable is defined in.  Another risk of setting variables is that
  1212. you may assign a value of a type that the compiler proved the variable
  1213. could never take on.  This may result in bad things happening.
  1214.  
  1215.  
  1216. 
  1217. File: cmu-user.info  Node: Note On Lexical Variable Access-Footnotes, Up: Note On Lexical Variable Access
  1218.  
  1219. (2) The variable bindings are actually created using the CMU Common Lisp
  1220. `symbol-macro-let' special form.
  1221.  
  1222. 
  1223. File: cmu-user.info  Node: Source Location Printing, Prev: Variable Access, Up: The Debugger, Next: Compiler Policy Control
  1224.  
  1225. Source Location Printing
  1226. ========================
  1227.  
  1228.  
  1229. One of CMU CMU Common Lisp's unique capabilities is source level debugging of compiled
  1230. code.  These commands display the source location for the current frame:
  1231.      
  1232. `source' [CONTEXT]     
  1233.      This command displays the file that the current frame's function
  1234.      was defined from (if it was defined from a file), and then the
  1235.      source form responsible for generating the code that the current
  1236.      frame was executing.  If CONTEXT is specified, then it is an
  1237.      integer specifying the number of enclosing levels of list structure
  1238.      to print.
  1239.      
  1240. `vsource' [CONTEXT]     
  1241.      This command is identical to `source', except that it uses the
  1242.      global values of `*print-level*' and `*print-length*' instead of
  1243.      the debugger printing control variables `*debug-print-level*' and
  1244.      `*debug-print-length*'.
  1245.  
  1246.  
  1247. The source form for a location in the code is the innermost list present
  1248. in the original source that encloses the form responsible for generating
  1249. that code.  If the actual source form is not a list, then some enclosing
  1250. list will be printed.  For example, if the source form was a reference
  1251. to the variable `*some-random-special*', then the innermost
  1252. enclosing evaluated form will be printed.  Here are some possible
  1253. enclosing forms:
  1254.      
  1255.      (let ((a *some-random-special*))
  1256.        ...)
  1257.      
  1258.      (+ *some-random-special* ...)
  1259.  
  1260.  
  1261. If the code at a location was generated from the expansion of a macro or a
  1262. source-level compiler optimization, then the form in the original source that
  1263. expanded into that code will be printed.  Suppose the file
  1264. `/usr/me/mystuff.lisp' looked like this:
  1265.      
  1266.      (defmacro mymac ()
  1267.        '(myfun))
  1268.      
  1269.      (defun foo ()
  1270.        (mymac)
  1271.        ...)
  1272.  
  1273. If `foo' has called `myfun', and is waiting for it to return, then the
  1274. `source' command would print:
  1275.      
  1276.      ; File: /usr/me/mystuff.lisp
  1277.      
  1278.      (MYMAC)
  1279.  
  1280. Note that the macro use was printed, not the actual function call form,
  1281. `(myfun)'.
  1282.  
  1283. If enclosing source is printed by giving an argument to `source' or
  1284. `vsource', then the actual source form is marked by wrapping it in a list
  1285. whose first element is `#:***HERE***'.  In the previous example, 
  1286. `source 1' would print:
  1287.      
  1288.      ; File: /usr/me/mystuff.lisp
  1289.      
  1290.      (DEFUN FOO ()
  1291.        (#:***HERE***
  1292.         (MYMAC))
  1293.        ...)
  1294.  
  1295.  
  1296.  
  1297. * Menu:
  1298.  
  1299. * How the Source is Found::     
  1300. * Source Location Availability::  
  1301.  
  1302.  
  1303. 
  1304. File: cmu-user.info  Node: How the Source is Found, Prev: Source Location Printing, Up: Source Location Printing, Next: Source Location Availability
  1305.  
  1306. How the Source is Found
  1307. -----------------------
  1308.  
  1309.  
  1310. If the code was defined from Common Lisp by `compile' or `eval', then
  1311. the source can always be reliably located.  If the code was defined from
  1312. a `fasl' file created by compile-file, then the debugger gets the source
  1313. forms it prints by reading them from the original source file.  This is
  1314. a potential problem, since the source file might have moved or changed
  1315. since the time it was compiled.
  1316.  
  1317. The source file is opened using the `truename' of the source file
  1318. pathname originally given to the compiler.  This is an absolute pathname
  1319. with all logical names and symbolic links expanded.  If the file can't
  1320. be located using this name, then the debugger gives up and signals an
  1321. error.
  1322.  
  1323. If the source file can be found, but has been modified since the time it was
  1324. compiled, the debugger prints this warning:
  1325.      
  1326.      ; File has been modified since compilation: ; FILENAME ; Using form
  1327.      offset instead of character position.
  1328.  
  1329. where FILENAME is the name of the source file.  It then proceeds using a
  1330. robust but not foolproof heuristic for locating the source.  This heuristic
  1331. works if:
  1332.      
  1333.    * No top-level forms before the top-level form containing the source have been
  1334.      added or deleted, and
  1335.      
  1336.    * The top-level form containing the source has not been modified much.  (More
  1337.      precisely, none of the list forms beginning before the source form have been
  1338.      added or deleted.)
  1339.  
  1340.  
  1341. If the heuristic doesn't work, the displayed source will be wrong, but
  1342. will probably be near the actual source.  If the "shape" of the
  1343. top-level form in the source file is too different from the original
  1344. form, then an error will be signalled.  When the heuristic is used, the
  1345. the source location commands are noticeably slowed.
  1346.  
  1347. Source location printing can also be confused if (after the source was
  1348. compiled) a read-macro you used in the code was redefined to expand into
  1349. something different, or if a read-macro ever returns the same `eq' list
  1350. twice.  If you don't define read macros and don't use `##' in perverted
  1351. ways, you don't need to worry about this.
  1352.  
  1353.  
  1354. 
  1355. File: cmu-user.info  Node: Source Location Availability, Prev: How the Source is Found, Up: Source Location Printing
  1356.  
  1357. Source Location Availability
  1358. ----------------------------
  1359.  
  1360.  
  1361. Source location information is only available when the `debug'
  1362. optimization quality is at least `2'.  If source location information is
  1363. unavailable, the source commands will give an error message.
  1364.  
  1365. If source location information is available, but the source location is
  1366. unknown because of an interrupt or unexpected hardware error
  1367. (*Note Unknown Locations and Interrupts::), then the command will print:
  1368.      
  1369.      Unknown location: using block start.
  1370.  
  1371. and then proceed to print the source location for the start of the basic
  1372. block enclosing the code location. It's a bit complicated to explain exactly what a basic block is, but
  1373. here are some properties of the block start location:
  1374.      
  1375.    * The block start location may be the same as the true location.
  1376.      
  1377.    * The block start location will never be later in the the program's
  1378.      flow of control than the true location.
  1379.      
  1380.    * No conditional control structures (such as `if', `cond', `or') will
  1381.      intervene between the block start and the true location (but note
  1382.      that some conditionals present in the original source could be
  1383.      optimized away.)  Function calls do not end basic blocks.
  1384.      
  1385.    * The head of a loop will be the start of a block.
  1386.      
  1387.    * The programming language concept of "block structure" and the CMU
  1388.      Common Lisp `block' special form are totally unrelated to the
  1389.      compiler's basic block.
  1390.  
  1391.  
  1392. In other words, the true location lies between the printed location and the
  1393. next conditional (but watch out because the compiler may have changed the
  1394. program on you.)
  1395.  
  1396.  
  1397. 
  1398. File: cmu-user.info  Node: Compiler Policy Control, Prev: Source Location Printing, Up: The Debugger, Next: Exiting Commands
  1399.  
  1400. Compiler Policy Control
  1401. =======================
  1402.  
  1403.  
  1404. The compilation policy specified by `optimize' declarations affects the
  1405. behavior seen in the debugger.  The `debug' quality directly affects the
  1406. debugger by controlling the amount of debugger information dumped.
  1407. Other optimization qualities have indirect but observable effects due to
  1408. changes in the way compilation is done.
  1409.  
  1410. Unlike the other optimization qualities (which are compared in relative value
  1411. to evaluate tradeoffs), the `debug' optimization quality is directly
  1412. translated to a level of debug information.  This absolute interpretation
  1413. allows the user to count on a particular amount of debug information being
  1414. available even when the values of the other qualities are changed during
  1415. compilation.  These are the levels of debug information that correspond to the
  1416. values of the `debug' quality:
  1417.      
  1418. `0'     
  1419.      
  1420.      Only the function name and enough information to allow the stack to
  1421.      be parsed.
  1422.      
  1423. `> 0'     
  1424.      
  1425.      Any level greater than `0' gives level `0' plus all argument
  1426.      variables.  Values will only be accessible if the argument variable
  1427.      is never set and `speed' is not `3'.  CMU Common Lisp allows any
  1428.      real value for optimization qualities.  It may be useful to specify
  1429.      `0.5' to get backtrace argument display without argument
  1430.      documentation.
  1431.      
  1432. `1'     
  1433.       Level `1' provides argument documentation (printed arglists) and
  1434.      derived argument/result type information.  This makes describe more
  1435.      informative, and allows the compiler to do compile-time argument
  1436.      count and type checking for any calls compiled at run-time.
  1437.      
  1438. `2'     
  1439.      
  1440.      Level `1' plus all interned local variables, source location
  1441.      information, and lifetime information that tells the debugger when
  1442.      arguments are available (even when `speed' is `3' or the argument
  1443.      is set.)  This is the default.
  1444.      
  1445. `3'     
  1446.      
  1447.      Level `2' plus all uninterned variables.  In addition, lifetime
  1448.      analysis is disabled (even when `speed' is `3'), ensuring that all
  1449.      variable values are available at any known location within the
  1450.      scope of the binding.  This has a speed penalty in addition to the
  1451.      obvious space penalty.
  1452.  
  1453.  
  1454. As you can see, if the `speed' quality is `3', debugger performance is
  1455. degraded.  This effect comes from the elimination of argument variable
  1456. special-casing (*Note Variable Value Availability::.)  Some degree of
  1457. speed/debuggability tradeoff is unavoidable, but the effect is not too
  1458. drastic when `debug' is at least `2'.
  1459.  
  1460. In addition to `inline' and `notinline' declarations, the relative
  1461. values of the `speed' and `space' qualities also change whether
  1462. functions are inline expanded (?.)  If a function is inline expanded,
  1463. then there will be no frame to represent the call, and the arguments
  1464. will be treated like any other local variable.  Functions may also be
  1465. "semi-inline", in which case there is a frame to represent the call, but
  1466. the call is to an optimized local version of the function, not to the
  1467. original function.
  1468.  
  1469.  
  1470. 
  1471.